|
Using pre-generated Java stubs for COM objects
can improve COM performance in some cases. It can also
enable access to some applications whose features are
not easily available to Java environments through
Microsoft Automation IDispatch interface.
Macromedia ColdFusion MX must access COM from the
Java environment. If you do not create Java Stubs to
access COM objects in advance, ColdFusion uses IDispatch
interface information to create mappings between COM and
Java. This mapping technique can have two disadvantages:
| • |
Doing the mapping takes time and can reduce
server performance with frequently-used complex
COM objects. |
| • |
The mapping technique cannot handle complex
COM interfaces where there are no simple mappings
between COM and Java or the object has multiple
IDispatch interfaces. For example, some standard
Microsoft applications cannot be handled
dynamically. |
To overcome these problems, ColdFusion MX
includes a utility, com2java.exe, that creates static
Java stub proxy classes for COM objects. ColdFusion can
use these Java stubs to access COM objects more
efficiently than when it maps COM to Java dynamically.
Additionally, the com2java utility can create stubs for
features that the dynamic proxy generator cannot
accommodate.
ColdFusion MX ships with pre-generated stubs for
the XP, 2000, and 97 editions of Microsoft Excel, Word,
and Access. ColdFusion is configured to automatically
use these stubs.
If you create Java stub files for a COM object,
you continue to use the cfobject tag with a type
attribute value of COM or the CreateObject function with
a first argument of COM, and you access the object
properties and methods as you normally do for COM
objects in ColdFusion.
WorkAround
Use
the following steps to use the com2java.exe utility and
install Java stubs for your COM object. This procedure
uses Microsoft Outlook as an example:
|
1 |
Configure your system as follows:
| • |
Ensure that a JDK (Java Development Kit)
is correctly installed, including proper
configuration of the CLASSPATH and the command
prompt PATH variable.
The command prompt PATH variable should point
to the bin directory under the installation path
for the JDK kit. |
| • |
Add cf_root/lib/jintegra.jar to
your CLASSPATH.
Note that cf_root is the
directory where ColdFusion is
installed. | |
|
2 |
In the Windows Start Menu, select Run and
type cmd. Make a new directory for the Java stub
files using the following command:
mkdir
C:\src\outlookXP
This directory can be temporary. You will
add files from the directory to a ColdFusion JAR
file. |
|
3 |
Run the
cf_root\Jintegra\bin\com2java.exe program
from a command line or the Windows Start Menu Run
dialog. A window appears. Do the following:
|
a |
Click the Select button. |
|
b |
Select your COM object’s Type Library or
dll. For OutlookXP, it is normally Program
Files\Microsoft
Office\Office10\MSOUTL.OLB. |
|
c |
Enter a package name in the Java package
field of in the com2java dialog box; for
example, outlookXP. This Java package will
contain all the classes for the Java stubs for
the COM object. You will use this package name
in step 7.
Note: Macromedia uses a
package name that starts with
coldfusion.runtime.com.com2java for the packages
that contain the pre-installed Java stubs for
Excel, Word, and Access. For example, the name
for the package containing the Microsoft Word XP
Java stub classes is
coldfusion.runtime.com.com2java.wordXP. This
package name hierarchy results in the wordXP
classes having a path inside the msapps.jar file
of
coldfusion\runtime\com\com2java\wordXP\className.class.
While
this naming convention is not necessary, you
should consider using a similar package naming
convention for clarity, if you use many COM
objects. |
|
d |
Click the Generate Proxies button to
display the File browser. Select the directory
you created in step 2, and click the file
browser dialog OK button to generate the stub
files. |
|
e |
Click Close to close the com2java
tool. | The files
generated in your directory include:
| • |
A Java interface and proxy class for each
COM interface |
| • |
A Java class for each COM
class |
| • |
A Java interface for each ENUM (a set of
constant
definitions) | |
|
4 |
Compile your Java code. In a command
prompt, do as follows:
|
a |
Make the directory that contains
the Java stubs (in this example,
C:\src\outlookXP) your working
directory. |
|
b |
Type following
line:
javac
-J-mx100m -J-ms100m *.java
The compiler switches ensure that you
have enough memory to compile all the necessary
files.
Note: If you did not put
jintegra.jar on your CLASSPATH in step 1, add
the switch -classpath: -classpath
cf_root/lib/jintegra.jar. | |
|
5 |
Ensure that ColdFusion Server is not
running.
To stop the ColdFusion Server in
Windows, open the Services control panel, select
the ColdFusion MX Application Server, and click
the Stop button. (On Windows 98 or Me, select Stop
ColdFusion MX from the ColdFusion MX Programs item
on the Start menu).
To stop the ColdFusion
Server in Unix, log in as root, make
cf_root/bin your working directory, and
enter the coldfusion stop command. |
|
6 |
Add your CLASS (.class) files to the
ColdFusion Microsoft application Java stubs file
by doing the following:
|
a |
In the Windows Command prompt, make the
parent directory of the directory that contains
your class files your working directory. In this
example, make c:\src your working director by
typing cd .. in the Command prompt from step
4. |
|
b |
Type following line:
jar -uvf
cf_root\lib\jarFile.jar
directoryName\*.class
Where:
cf_root is the directory where
ColdFusion MX is installed.
jarFile is the name of the jar
file in which to put the stubs. The
pre-generated stub files that are shipped by
ColdFusion are located in msapps.jar. You can
add your stubs to this jar file or specify a new
jar file. If you use you own jar file, you
ensure that a future ColdFusion installation
will not remove your Java stubs.
directoryName is the name of the
Directory that contains the class
files. For the OutlookXP example, type the
following line:
jar -uvf
cf_root\lib\msapps.jar
directoryName\*.class
| |
|
7 |
Update the cf_root
/lib/neo-comobjmap.xml file by appending your
object definition to the list. The object
definition consists of the following lines:
<var
name="progID">
<string>PackageName.mainClass</string>
</var>
Where ProgID is the COM object
ProgID value, PackageName is the package name
you specified in step 3c, and mainClass
is the main class of the COM object. The main
class contains the methods you invoke. For many
Microsoft applications, this class is Application.
In general, the largest class file created in step
4 is the main class.
In the example in this
TechNote, to add Outlook XP to the
neo-comobjmap.xml file, add the lines in bold text
before the closing </struct>
tag:
<var
name="access.application.9">
<string>coldfusion.runtime.com.com2java.access2k.Application</string>
</var>
<var
name="outlook.application.10">
<string>outlookXP.Application</string>
</var>
</struct>
In this example, outlook.application.10 is
the progID of the Outlook XP COM object, outlookXP
is the package name you specified in step 3c, and
Application is the COM object’s main class. To
create the COM object in ColdFusion, you use a
line such as the following.
<cfobject type="COM"
name="myOutlook"
class="outlook.application.10"
action="CREATE">
|
|
8 |
Restart ColdFusion Server: Open the
Services control panel, select ColdFusion MX
Application Server, and click the Start
button. |
|
9 |
After you have installed the stubs, you can
delete the directory you created in step 2,
including all its
contents. |
Related TechNotes:
|
|
| Products: |
ColdFusion
|
| Browser: |
N/A
|
| Server: |
N/A
|
| Platform: |
N/A
|
| OS: |
Windows
2000
Windows
98
Windows NT
4.0
Windows
XP
|
| Database: |
N/A
|
| |
.gif){kind=tracking}